mudbox::Stream Class Reference

#include <stream.h>

Inheritance diagram for mudbox::Stream:

Detailed Description

Streams are used to read information from a file, or to write it to a file.

In a Mudbox plug-in, you would typically use the Stream class when you override the Serialize method of a custom node that you have derived from the Node class. When you save or load a scene, Mudbox will call that method and pass you a stream object, which you can then use.

Typically, a stream object is used like this:

        void myNode::Serialize( Stream& s )
        {
            myParentClass::Serialize(s);
            s == myVariable1 == myVariable2 == myVariable3;
        }

Here, the "==" operator will store the variables in the stream (if the stream is writing), or read them from the stream (if it is reading). So you can use the same code for both reading and writing. Since the "==" operator returns a stream reference, you can serialize multiple variables on the same line if you wish to do so, as shown above.


Public Types
enum	{ chunk = 0x800000 }
Public Member Functions
virtual const mudbox::ClassDesc *	RuntimeClass (void) const
virtual	~Stream (void)
	Destructor.
virtual QString	FileName (void) const
	Returns the name of the file.
virtual bool	IsValid (void)
	Returns true if the stream has a valid version number.
virtual bool	IsOlderThan (int iVersion) const
	(Deprecated) Checks if the file is older than a specified version. Returns true if it is.
virtual bool	IsNewerThan (int iVersion) const
	(Deprecated) Checks if the file is newer than a specified version.
virtual int	ClassVersion (const class ClassDesc *pClass) const
	Returns the version for a class inside the current stream.
template<typename Type>
bool	IsOlderThan (int iVersion, Type *pClassInstance) const
	Checks if the file is older than a specified version for the given class. Returns true if it is.
template<typename Type>
bool	IsNewerThan (int iVersion, Type *pClassInstance) const
	Checks if the file is newer than a specified version for the given class.
virtual bool	IsStoring (void) const
	Returns true if the stream is in storing mode (i.e.
virtual void	SetError (bool bError)
	Use this method to inform Mudbox that there is an error in the stream you are trying to read or write.
virtual int	Version (void) const
	Returns the version number of the stream.
virtual uint64	CurrentPosition (void) const
	Returns the current position in the file. See also SetCurrentPosition().
virtual void	SetCurrentPosition (uint64 iPosition)
	Sets the current position in the file.
virtual void	ReportCorruption (void)
	Call this function from your Serialize implementation, if you detect that the file content is corrupt.
virtual void	Open (const QString &sFileName, bool bStoring=false, int iProjectedFileSize=0, bool bProgressBar=true)
	Opens the file attached to this stream.
virtual void	Reopen (bool bStoring=false)
	Re-opens the file attached to this stream.
virtual bool	Close (void)
	Closes the file attached to this stream. Returns true if the operation succeed.
virtual bool	Eof (void)
	Returns true if you are reading the file, and you have reached the end of it.
virtual bool	ReadContents (void)
	This function reads the content of the stream into the memory, when the stream is opened for read.
virtual size_t	Read (void *pBuffer, size_t iSize)
	Reads data directly from the stream into a buffer you provide.
virtual size_t	Write (const void *pBuffer, size_t iSize)
	Writes data to the stream from a buffer you provide.
int	ReadInt (void)
	Reads a single integer from the stream, and returns it.
virtual void	ReadToFile (const char *sFile)
	Takes the entire contents of the stream and writes it into the specified file.
virtual void	WriteFromFile (const char *sFile)
	Fills the stream with the content of the specified file.
template<typename type>
Stream &	operator>> (type &v)
	Reads data from the stream to any data type.
template<typename type>
Stream &	operator<< (const type &v)
	Stores any data type into the stream.
virtual Node *	ReadPointer (void)
	Read/Writes node pointers.
virtual void	WritePointer (Node *pPointer)
template<typename type>
Stream &	operator>> (type *&p)
	Reads a pointer from the file.
template<typename type>
Stream &	operator<< (type *&p)
	Writes a pointer into the stream.
template<typename type>
Stream &	operator>> (Store< type > &s)
	Reads data from the stream to any Store (array) type.
template<typename type>
Stream &	operator<< (const Store< type > &s)
	Writes any store type (array) to the stream.
Stream &	operator>> (QString &s)
	Read/Writes QString.
Stream &	operator<< (const QString &s)
template<typename type>
Stream &	operator>> (QVector< type > &s)
	Reads data from the stream to a QVector object.
template<typename type>
Stream &	operator<< (const QVector< type > &s)
	Writes any store type (array) to the stream.
Static Public Member Functions
const mudbox::ClassDesc *	StaticClass (void)
mudbox::Node *	CreateInstances (unsigned int iCount=1)
Protected Member Functions
	Stream (void)
	You cannot create a Stream object directly. Call CreateInstance<Stream>(), then use Stream::Open to specify parameters.

Member Enumeration Documentation

anonymous enum

Enumeration values:

chunk

00050 { chunk = 0x800000 };

Constructor & Destructor Documentation

mudbox::Stream::Stream ( void ) [protected]

You cannot create a Stream object directly. Call CreateInstance<Stream>(), then use Stream::Open to specify parameters.

virtual mudbox::Stream::~Stream ( void ) [virtual]

Destructor.

Member Function Documentation

virtual const mudbox::ClassDesc* mudbox::Stream::RuntimeClass ( void ) const [inline, virtual]

Reimplemented from mudbox::Node.

00045 :

const mudbox::ClassDesc* mudbox::Stream::StaticClass ( void ) [static]

Reimplemented from mudbox::Node.

mudbox::Node* mudbox::Stream::CreateInstances ( unsigned int iCount = 1 ) [static]

Reimplemented from mudbox::Node.

virtual QString mudbox::Stream::FileName ( void ) const [virtual]

Returns the name of the file.

virtual bool mudbox::Stream::IsValid ( void ) [virtual]

Returns true if the stream has a valid version number.

When Mudbox creates a new stream for writing, it gives the stream its version number. Similarly, if a stream is opened for reading, it has a version number. This method checks to see if the number is valid.

The version number can be invalid if there is a problem with the file, or if the file was saved in a newer version of Mudbox, and you are trying to read it into an older version.

virtual bool mudbox::Stream::IsOlderThan ( int iVersion ) const [virtual]

(Deprecated) Checks if the file is older than a specified version. Returns true if it is.

Typically this method is used during Serialize to handle changes to the file format between versions of the software. This function is deprecated. Use the class specific one with the same name instead.

Parameters:

iVersion

[in] The version number you want to compare

virtual bool mudbox::Stream::IsNewerThan ( int iVersion ) const [virtual]

(Deprecated) Checks if the file is newer than a specified version.

Returns true if it is, false if it is not. Typically this method is used during Serialize() to handle changes to the file format between versions of the software. This function is deprecated. Use the class specific one with the same name instead.

Parameters:

iVersion

[in] The version number you want to compare

virtual int mudbox::Stream::ClassVersion ( const class ClassDesc * pClass ) const [virtual]

Returns the version for a class inside the current stream.

This function returns the version number which was used for a class when the stream was created. If the stream is a storing stream, then this number equals to the current version of the class.

template<typename Type>
bool mudbox::Stream::IsOlderThan	(	int	iVersion,
		Type *	pClassInstance
	)	const `[inline]`

Checks if the file is older than a specified version for the given class. Returns true if it is.

Typically this method is used during Serialize to handle changes to the file format between versions of the software.

Normally, you call this function within your Serialize implementation, something like this:

        if ( s.IsOlderThan( 5, this );

In this example the specified version number (5) is a local version number to your class, while the second parameter just identifies the class where you are calling the function. See the macro IMPLEMENT_SCLASS for more details.

Parameters:

iVersion	[in] The version number you want to compare
pClassInstance	[in] An instance of the class which should be tested

00109                              { return ClassVersion( Type::StaticClass() ) < iVersion; };

template<typename Type>
bool mudbox::Stream::IsNewerThan	(	int	iVersion,
		Type *	pClassInstance
	)	const `[inline]`

Checks if the file is newer than a specified version for the given class.

Returns true if it is, false if it is not. Typically this method is used during Serialize() to handle changes to the file format between versions of the software.

Normally, you call this function within your Serialize implementation, something like this:

        if ( s.IsNewerThan( 4, this );

In this example the specified version number (4) is a local version number to your class, while the second parameter just identifies the class where you are calling the function. See the macro IMPLEMENT_SCLASS for more details.

Parameters:

iVersion	[in] The version number you want to compare
pClassInstance	[in] An instance of the class which should be tested

00127                              { return ClassVersion( Type::StaticClass() ) > iVersion; };

virtual bool mudbox::Stream::IsStoring ( void ) const [virtual]

Returns true if the stream is in storing mode (i.e.

writing a file), and false if it is in reading mode.

virtual void mudbox::Stream::SetError ( bool bError ) [virtual]

Use this method to inform Mudbox that there is an error in the stream you are trying to read or write.

virtual int mudbox::Stream::Version ( void ) const [virtual]

Returns the version number of the stream.

Reimplemented from mudbox::Node.

virtual uint64 mudbox::Stream::CurrentPosition ( void ) const [virtual]

Returns the current position in the file. See also SetCurrentPosition().

virtual void mudbox::Stream::SetCurrentPosition ( uint64 iPosition ) [virtual]

Sets the current position in the file.

Further calls to the stream will serialize from the new location. You can use this to skip over data in the file that you don't currently need.

Parameters:

iPosition

[in] The byte address to jump to

virtual void mudbox::Stream::ReportCorruption ( void ) [virtual]

Call this function from your Serialize implementation, if you detect that the file content is corrupt.

This function will throw an exception, so don't expect it to return. This call basically cancels the serialization of the current node and will try to step to the next one.

virtual void mudbox::Stream::Open	(	const QString &	sFileName,
		bool	bStoring = `false`,
		int	iProjectedFileSize = `0`,
		bool	bProgressBar = `true`
	)	`[virtual]`

Opens the file attached to this stream.

After creating a Stream object, this is the first function you normally call, which initializes the stream.

Parameters:

sFileName	[in] The name of the file to be opened
bStoring	[in] Set this to true if you are storing data (i.e. writing the file), and false otherwise
iProjectedFileSize	[in] If you know how big your file will be, you can optionally specify this argument to help display the status bar correctly
bProgressBar	[in] If true, a progress bar will be displayed while reading and writing the file.

virtual void mudbox::Stream::Reopen ( bool bStoring = false ) [virtual]

Re-opens the file attached to this stream.

Parameters:

bStoring

[in] If true, open the file for writing. If false, open it for reading.

virtual bool mudbox::Stream::Close ( void ) [virtual]

Closes the file attached to this stream. Returns true if the operation succeed.

This function is automatically called when the stream object is deleted. You can call this function directly before destructing the stream object, if you want to know about any corruption during writing, in which case this function returns false.

virtual bool mudbox::Stream::Eof ( void ) [virtual]

Returns true if you are reading the file, and you have reached the end of it.

virtual bool mudbox::Stream::ReadContents ( void ) [virtual]

This function reads the content of the stream into the memory, when the stream is opened for read.

This function is called automatically when the first pointer is serialized from the stream. You can directly call this function right after opening the stream, if you would like to know if the stream is loaded properly, or corruption was detected.

virtual size_t mudbox::Stream::Read	(	void *	pBuffer,
		size_t	iSize
	)	`[virtual]`

Reads data directly from the stream into a buffer you provide.

This method returns the number of bytes that were successfully transferred to the buffer. (This number can be different if there is an error, or if you reach the end of the file-- IS THIS TRUE?)

Parameters:

pBuffer	[in] A pointer to a block of memory to hold the data
iSize	[in] The number of bytes to be read

virtual size_t mudbox::Stream::Write	(	const void *	pBuffer,
		size_t	iSize
	)	`[virtual]`

Writes data to the stream from a buffer you provide.

Returns the number of bytes written.

Parameters:

pBuffer	[in] A pointer to a buffer of data you want to write
iSize	[in] The number of bytes you want to write

int mudbox::Stream::ReadInt ( void ) [inline]

Reads a single integer from the stream, and returns it.

00207 { int i; operator >>( i ); return i; };

virtual void mudbox::Stream::ReadToFile ( const char * sFile ) [virtual]

Takes the entire contents of the stream and writes it into the specified file.

Parameters:

sFile

[in] The name of the file that you want to store the stream data in

virtual void mudbox::Stream::WriteFromFile ( const char * sFile ) [virtual]

Fills the stream with the content of the specified file.

Parameters:

sFile

[in] The name of the file that you want the stream to get its data from.

template<typename type>
Stream& mudbox::Stream::operator>>	(	type &	v	)	`[inline]`

Reads data from the stream to any data type.

00222 { MB_VERIFY_EQ( Read( &v, sizeof(type) ), sizeof(type) ); return *this; };

template<typename type>
Stream& mudbox::Stream::operator<<	(	const type &	v	)	`[inline]`

Stores any data type into the stream.

00226 { MB_VERIFY_EQ( Write( &v, sizeof(type) ), sizeof(type) ); return *this; };

virtual Node* mudbox::Stream::ReadPointer ( void ) [virtual]

Read/Writes node pointers.

virtual void mudbox::Stream::WritePointer ( Node * pPointer ) [virtual]

template<typename type>
Stream& mudbox::Stream::operator>>	(	type *&	p	)	`[inline]`

Reads a pointer from the file.

This function will serialize any pointer whose target is an object whose class was derived from the Node class. Other kind of pointers (like int*) cannot be serialized.

00236 { p = dynamic_cast<type *>( ReadPointer() ); return *this; };

template<typename type>
Stream& mudbox::Stream::operator<<	(	type *&	p	)	`[inline]`

Writes a pointer into the stream.

This function writes a pointer to the stream, if the pointer target is an object whose class was derived from the Node class. Other kind of pointers cannot be serialized.

00243 { WritePointer( p ); return *this; };

template<typename type>
Stream & mudbox::Stream::operator>>	(	Store< type > &	s	)	`[inline]`

Reads data from the stream to any Store (array) type.

00302 { unsigned int iSize; (*this) >> iSize; if ( o.SetItemCount( iSize ) && iSize ) Read( &(o[0]), sizeof(type)*iSize ); return *this; };

template<typename type>
Stream & mudbox::Stream::operator<<	(	const Store< type > &	s	)	`[inline]`

Writes any store type (array) to the stream.

00300 { (*this) << o.ItemCount(); Write( &(o[0]), sizeof(type)*o.ItemCount() ); return *this; };

Stream& mudbox::Stream::operator>>

(

QString &

)

Read/Writes QString.

Stream& mudbox::Stream::operator<<

(

const QString &

)

template<typename type>
Stream& mudbox::Stream::operator>>	(	QVector< type > &	s	)	`[inline]`

Reads data from the stream to a QVector object.

This function only works for arrays which contain simple objects only, which means the object has no pointers.

00262     {
00263         int iSize = ReadInt();
00264         s.resize( iSize );
00265         Read( s.data(), iSize*sizeof(type) );
00266         return *this;
00267     };

template<typename type>
Stream& mudbox::Stream::operator<<	(	const QVector< type > &	s	)	`[inline]`

Writes any store type (array) to the stream.

This function only works for arrays which contain simple objects only, which means the object has no pointers.

00274     {
00275         (*this) << s.size();
00276         Write( s.data(), s.size()*sizeof(type) );
00277         return *this;
00278     };

mudbox::Stream Class Reference

Detailed Description

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation